<HTML><HEAD><TITLE>store_set(+StoreHandle, ++Key, ?Value)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Non-logical Variables, Arrays, Bags, Shelves and Stores</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>store_set(+StoreHandle, ++Key, ?Value)</H1>
Make an entry into a store object
<DL>
<DT><EM>StoreHandle</EM></DT>
<DD>A store handle or store name
</DD>
<DT><EM>Key</EM></DT>
<DD>A ground term
</DD>
<DT><EM>Value</EM></DT>
<DD>An arbitrary term
</DD>
</DL>
<H2>Description</H2>
	This stores an arbitrary ECLiPSe term under a given key into
	the given store object. If an entry for this key already exists,
	it will be replaced by the new entry. 
<P>
	The key can be arbitrarily complex, but must be a ground term.
	The value can be an arbitrary term, and may contain uninstantiated
	variables. Note that values are copied when being stored or
	retrieved, therefore a retrieved nonground value will contain
	fresh variables rather than the original ones (this is similar
	to the behaviour of bags, shelves and global variables).
<P>
	The complexity of the store operation is linear in both the size
	of the key and the value, since both are being copied. For indexing
	purposes, a hash value is computed from the key, and the full depth
	of the key is taken into account.
<P>
	Note: If StoreHandle is not a handle, then it must be an atom or a
	compound term, and the store is identified by this term's toplevel
	functor together with the context module.
<P>
    
<H3>Modes and Determinism</H3><UL>
<LI>store_set(+, ++, ?) is det
</UL>
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>StoreHandle is uninstantiated
<DT><EM>(4) instantiation fault </EM>
<DD>Key is not ground
<DT><EM>(5) type error </EM>
<DD>StoreHandle is neither atom nor compound term nor store handle
<DT><EM>(45) record does not exist </EM>
<DD>StoreHandle is not the name of a store
</DL>
<H2>Examples</H2>
<PRE>

    ?- store_create(Handle),
       store_set(Handle, tom, 12345),
       store_set(Handle, name(dick,tracy), phone(42376,home)),
       store_set(Handle, numbers:prime, [2,3,5,7|_More]),
       stored_keys_and_values(Handle, Data).

    Handle = 'STORE'(16'003130e8)
    Data = [(numbers : prime) - [2, 3, 5, 7|_123],
            tom - 12345,
	    name(dick, tracy) - phone(42376, home)]
    Yes (0.00s cpu)
    </PRE>
<H2>See Also</H2>
<A HREF="../../kernel/storage/store-1.html">store / 1</A>, <A HREF="../../kernel/modules/local-1.html">local / 1</A>, <A HREF="../../kernel/storage/store_erase-1.html">store_erase / 1</A>, <A HREF="../../kernel/storage/store_get-3.html">store_get / 3</A>, <A HREF="../../kernel/storage/store_delete-2.html">store_delete / 2</A>, <A HREF="../../kernel/storage/store_contains-2.html">store_contains / 2</A>, <A HREF="../../kernel/storage/stored_keys-2.html">stored_keys / 2</A>, <A HREF="../../kernel/storage/stored_keys_and_values-2.html">stored_keys_and_values / 2</A>, <A HREF="../../kernel/storage/store_create-1.html">store_create / 1</A>, <A HREF="../../kernel/storage/store_count-2.html">store_count / 2</A>, <A HREF="../../kernel/storage/store_inc-2.html">store_inc / 2</A>
</BODY></HTML>
